PC Media 6

home *** CD-ROM | disk | FTP | other *** search

/ PC Media 6 / PC MEDIA CD06.iso / share / prog / multi_c1 / multi_c.doc < prev next >

Wrap

Text File | 1995-01-01 | 57.3 KB | 2,311 lines

MULTI-APP V1.0.1 ============================== ______________________________ ============================== Documentation Rev 0.3 Copyright 1992 by Jeff Heaton MULTI-APP V1.0 A MicroGenesis Product Copyright 1992 by Jeff Heaton All Rights Reserved MicroGenesis Software P.O. Box No 25534 St. Louis, MO 63125 VOICE: (314) 638-2506 DATA:(314) 638-5205 n,8,1,1200-9600 Part I: The Multi-APP Core Introduction The MULTI-APP core is the heart of the MULTI-APP system. All classes in the MULTI-APP system are derived from these "core classes." The primary purpose of this core is to give all MULTI-APP classes a consistent interface. Many abstract classes(who se sole purpose is to define future classes) are defined here, as well as real classes for file and data handling. Using the MULTI-APP core you can provide your application with platform-independent access to the basic system resources that all applications need. These are the file system, the serial ports, and basic data structure handling. In addition a spec ial "error free" compression based communications protocol is provided to allow you to access other MULTI-APP applications and share information remotely. In addition to providing these basic services, MULTI-APP core allows you to use the MULTI-APP user interface package to produce GUI(graphic user interface) applications in a platform-independent manner. MultiApp Core Features: I. Platform Independent Access to Files: A. DEVICE compatible for I/O redirection B. Allows concurrent shared access of files C. Buffered character access provides maximum speed D. Fast block read/write functions for record handling II. Platform Independent Access to Serial Ports: A. DEVICE compatible for I/O redirection B. Optional Compression/Error correction(in SOFTWARE) C. Access to all hardware lines provided by host computer III. Misc Platform Independent Services: A. Integer stacks B. Base classes for linked lists C. File Maintenance functions License The MultiApp system is currently being marketed as ShareWare. Shareware is a unique software distribution method where you, the software user, gets to try out the program BEFORE you pay for it. This is a FULL version of the MultiApp core, and you get a FULL copy of the text representation of the user manual to evaluate for a time period of 30(thirty) days. If you wish to continue using MultiApp after this trial period, or if you publicly release a program(commercial,shareware, public domain or any other non-personal use) you MUST register your copy. Upon registration you will receive the complete source code to the MultiApp product that you registered. The source code, however, will be for your exclusive use and may not be distributed directly. However, applications can be created using source code modifications. If you use MultiApp beyond the initial 30 day limit, or publicly release any application that contains MultiApp code you MUST have registered MultiApp. To do otherwise is a direct violation of the MultiApp copyright. However once you have register ed a MultiApp product you may use it in your own application, royalty free, for as many applications as you wish. The following information is not in classes and provide miscellaneous utility to the MULTI-APP system. Some of the data structures defined here are only used in the MULTI-APP user interface and are thus only briefly described. Contacting MicroGenesis: Compuserve : 76476,1701 America On-Line : JeffH66 InterNet : S108955@UMRVMA.UMR.EDU Voice : (314) 638-2506 BBS : (314) 638-1731 Compiler Considerations: If you want to maximize portablilty between various computer platforms MultiApp can greatly speed this process. However because even C/C++ compilers interpret the C/C++ standard differently you must account for these differences in your code. Thes e are generally only syntactical errors that will show up when you compile your application on another platform for the first time. MultiApp does not use pure c++ as its coding standard. Pure C++ can defiantly be used with MultiApp but since many platforms(particularly the Macintosh) are lacking in the area of quality C++ compilers we have developed MultiApp based on a simpler subset of C++. This is based on Symantec Think C 5's objects extension. This is basically identical to C++ but without some of C++'s more complex features. IF you want your application to be directly compilable on object based C compilers you shou ld not use the following C++ features: Function Overloading Operator Overloading Function Templates Parameters To Constructors Static Objects(ie MYOBJECT obj; is illegal it MUST be MYOBJECT *obj) this redefinition(this=this->next is illegal, all other standard this operations are legal however). All Functions MUST have prototypes. Cast all pointer conversions These are some general rules to follow to ensure that your programs are compatible with Object C type compilers as well as True C++ compilers. Once multiApp is ported into C++ compilers on both Dos and Mac these restrictions will not be necessary. We are currently working on creating a MPW version of MutliApp that will support full C++, but for now please remember that not all platforms have as "developed" of a base of C++ compilers as the IBM platform does. If you are going to be seriously developing cross-platform applications than it is suggested that you own a copy of BOTH Borland/Turbo C++ and Think C so you can see the differences for yourself. I have not found it to be too much of a problem in o ur own development. Just treat Think C as the "least common denominator" and you will do fine. We will also be coming out with a document further describing Think C/Borland C++ compatibility with the release of MultiApp UI. Global Functions: void beep(void); This function will cause the users computer to beep. void c2pas(char *str); This function will transform str into a pascal string(assuming it was originally a c string). void pas2c(char *str); This function will transform str into a c string(assuming it was originally a pascal string). void sleep(int tenths); This function will wait for tenths 1/10ths of a second. int timer_check(long tm); Call this function,with the value timer_set returns, to see if the time is up. If that time has elapsed then this function returns true. long timer_set(int tenths); Sets a timer for tenths 1/10ths of a second. The value that this function returns should be passed to timer_check to determine if that time has elapsed. void timer_wait(long tm); Call this function with the value timer_set returns to wait until that amount of time elapses. void updcrc(unsigned char b); Each call of this function causes b to be calculated into the global crc. extern unsigned short crc; This variable is used with updcrc to calculate a CRC value. After you are done feeding updcrc your bytes, this is the variable you get your final CRC from. Definitions: The following are some general integer to binary conversion functions that allow MULTI-APP data to be compatible across platforms(especially since Intel and Motorola store ints exactly backwards of each other): #define HI_BYTE(x) (x/256) #define LO_BYTE(x) (x-(HI_BYTE(x)*256)) #define BYTE_COMB(x,y) ((x*256)+y) CLASS NAME: ATOM PARENT: NONE IMPORTANT CHILDREN: almost the whole library. Definition: class ATOM { public: ATOM(); ATOM *next;// Next atom in a linked list }; Description: The most fundamental class of MULTI-APP is the atom class. Every object in the MULTI-APP library is derived from the atom class. This allows general purpose "data container classes" to be defined for the atom. These data container classes can then be used for other object types as well. The most important of these data container classes is the linked list class(LIST). In its simplest form LIST allows a linked list of ATOM's, but because WINDOW classes are derived from ATOM it is possibl e to create a linked list of WINDOWs or any other descendant of the ATOM class. Member Functions: ATOM(); Description: CONSTRUCTOR - simply sets next equal to NULL. Returns: nothing See Also: Example: int search_for(ATOM *first,ATOM *lookfor) { // Search the linked list pointed to by "first" for // "lookfor". Return TRUE if found while(first!=NULL) { if(first==lookfor)// Found it yet? return TRUE; first=first->next;// Next atom in list } } Data Members: ATOM *next; The next ATOM in the linked list. CLASS NAME: LIST PARENT: ATOM IMPORTANT CHILDREN: APP(from the user interface) Definition: class LIST:public ATOM { public: LIST(void); void add(ATOM *atom); void del(ATOM *atom); void first_element(void); void forward(void); void pos(long p); virtual int comp(ATOM *a1,ATOM *a2); ATOM *first,*current; }; Description: The LIST object is one of the primary classes of MULTI-APP. LIST is a "data container object" designed to hold a linked list of ATOMS. Because almost every object in MULTI-APP is derived from ATOM, lists can be built of many different types of obj ects. For example in the MULTI-APP User Interface section you will learn that the APP class is really a linked list of all open windows. Because APP is a child of LIST it can build lists of ANYTHING that is derived from ATOM. This includes windows , dialogs and many other types of screen objects. Data Members: ATOM *first; This is the first ATOM in the linked list. This gives LIST a starting point for list resets and searches. If the list is empty then this variable contains a NULL. ATOM *current; Current is the atom that the list is currently processing. It is perfectly legal for current to be NULL, even if the list has data in it. A NULL current usually means that you have reached the end of the list. Member Functions: LIST(void); Description: CONSTRUCTOR - This sets current and first to NULL, thus creating a new blank LIST. Returns: nothing See Also: ATOM Example: void main(void) { LIST *list;// The list we will be adding items to ATOMS *a,*b,*c; // Some atoms to add list=new LIST; list->add(a=new ATOM); list->add(b=new ATOM); list->add(b=new ATOM); // At this point the list would look something like: // a-->b-->c-->NULL list->del(b); // At this point the list would look something like: // a-->c-->NULL // Now loop through the list first_element(); while(current!=NULL) forward(); } _________________________________________________________ void add(ATOM *atom); Description: atom - The atom being added to list. This function adds a new ATOM into the list. The comp function is used to determine atom's position. If comp is not redefined then the atom is inserted at the end of the list. Returns: nothing See Also: del Example for LIST class. Example: void MYOBJECT::add(ATOM *atom) {// An add function for a derived LIST manager MYITEM *i=(MYITEM*)atom; // Now use "i" to officially add your type of object // This is usually some sort of inititilaztion LIST::add(atom);// Add it to the actual list } _________________________________________________________ virtual int comp(ATOM *a1,ATOM *a2); Description: a1 - The atom on the left side of the comparison a2 - The atom on the right side of the comparison This function compares a1 to a2 and returns: 0 Both ATOMS are equal. >1 a1 is greater than a2 <1 a2 is greater than a1 Comp is used to sort ATOMS as they enter the list. Returns: nothing See Also: forward() Example for LIST class. Examples: // A compare function(the default) that will insert items into the list in reverse order. int class::comp(ATOM *a1,ATOM *a2){ return 1; } // A compare function that will insert items in the same order they are entered int class::comp(ATOM *a1,ATOM *a2){ return -1; } _________________________________________________________ void del(ATOM *atom); Description: atom - The atom being removed from the list. This function removes an ATOM from the list. Please note that the memory for atom is not freed, but rather the ATOM is simply pulled out of the list chain. Returns: nothing See Also: add Example for LIST class. Example: void MYOBJECT::del(ATOM *atom) {// An del function for a derived LIST manager MYITEM *i=(MYITEM*)atom; // Now use "i" to officially remove your type of object // This is usually some sort of shutdown sequence LIST::del(atom);// Add it to the actual list } _________________________________________________________ void first_element(void); Description: This function sets current to first, thus moving the lists attention to its first element. This function is usually called prior to a search. Returns: nothing See Also: forward() Example for LIST class. _________________________________________________________ void forward(void); Description: This function moves the current pointer to the next ATOM in the list. If there are no more ATOMs or the list is empty then current is set to NULL. Returns: nothing See Also: first_element() Example for LIST class. _________________________________________________________ void pos(long p); Description: p - element in list to move to. This function moves(points current to) the "p"th element in the linked list. Returns: nothing See Also: forward CLASS NAME: DEVICE PARENT: LIST IMPORTANT CHILDREN: FILEIO, and any device class made for MULTI-APP Definition: class DEVICE:public LIST { public: virtual int put(BYTE ch); virtual int putstr(char *str); virtual int goxy(int x,int y); virtual int inverse(void); virtual int normal(void); virtual BYTE get(BYTE *ch); virtual BYTE wait2get(BYTE *ch); virtual int hit(void); virtual int reset(void); virtual int ceol(void); virtual int wherex(void); virtual int wherey(void); virtual int printf(char *format,...); int getstr(char *str); }; Description: DEVICE is a object that defines basic properties that any MULTI-APP compatible device should have. DEVICE allows MULTI-APP to communicate to a device in a polled 8-bit manner. Commands are provided to do basic byte I/O as well as some general cont rol commands that many "video" devices would have. The commands provided here are the same on ALL the children of DEVICE. So as a result the command to print a string is identical in all parts of MULTI-APP. Data Members: NONE Member Functions: virtual int ceol(void); Description: Ceol is only used in video devices, it will clear to the end of the line starting at wherex,wherey. Returns: nonzero on error. See Also: reset. _________________________________________________________ int getstr(char *str); Description: str - the string read from the device. This function will input characters into the string str until a carriage return(#13) is received. The final carriage return is not stored in the string. If the operation is successful this function will return a zero. Returns: nonzero on error. See Also: _________________________________________________________ virtual BYTE get(BYTE *ch); Description: ch - if NULL does nothing, otherwise the BYTE read. This function receives the next 8-bit character from the device. If none are available then this function returns a zero. There are two paths by which this function returns its data. First is through the normal function return, and second is via a pointer to a BYTE. If you do not wish to use the pointer method simply call it as "get(NULL)". Example: "x=get(NULL)", "get(&x)" and "x=get(&x)" all do exactly the same thing. Returns: character read, or a zero if none are available. See Also: put,getstr,wait2get,hit. Example: BYTE DEVICE::wait2get(BYTE *ch) { BYTE c; while(!hit());// Loop until something is available c=get(NULL);// Input character if(ch!=NULL)// Return by pointer if necessary *ch=c; return(c); } _________________________________________________________ virtual int goxy(int x,int y); Description: x - The horizontal position to goto. y - The vertical position to goto. This function allows you to set the x and y coordinates of the device. Not all devices have x/y coordinates, so this function is not used in all DEVICES. If the operation is successful this function will return a zero. Returns: nonzero on error. See Also: reset. Example: void home(DEVICE *d) {// Home the cursor in any device(if it supports cursors) d->goxy(0,0); } _________________________________________________________ virtual int hit(void); Description: Hit allows you to determine if there is a character waiting to be received(by one of the input functions). Hit returns 0 if none are available. If data is waiting it returns the number of bytes waiting. Returns: true if there is a character waiting to be read. See Also: get,wait2get. Example: see get. _________________________________________________________ virtual int inverse(void); Description: If the device is capable of having its foreground and background colors inverted this function inverses them. If the operation is successful then this function will return a zero. Inverse is left over from before MULTI-APP supported color, and i s rarely used anymore. Returns: nonzero on error. See Also: normal. _________________________________________________________ virtual int normal(void); Description: This function resets any special modes(namely inverse) that may have been set on this device. If the operation is successful this function will return a zero. Returns: nonzero on error. See Also: inverse. _________________________________________________________ virtual int printf(char *format,...); Description: format - "stdio.h printf" format string to write. This output function allows you to output to a device in the classic C printf style. Consult your C reference manual if you require additional information on printf. Please note that the final outputted string cannot be larger than 199 characters , if it is the results are undefined. Returns: nonzero on error. See Also: put,putstr. Example: void main(void) { DEVICE *device; device=new DEVICE; device->goxy(10,10);// Move cursor device->printf("Cursor is at: %xi,%i.",// Display cursor's location device->wherex(),device->wherey()); } _________________________________________________________ virtual int put(BYTE ch); Description: ch - the character to be written. This function will attempt to write a single character to the device. If the operation is successful this function will return a zero. Returns: nonzero on error. See Also: putstr,printf. Example: void spc(DEVICE *device,int i) {// write out i spaces(32) to any type of device while(i--) d->put(32); } _________________________________________________________ virtual int putstr(char *str); Description: str - the string to be written. This function repeatedly calls put until a zero is reached in the string. If the operation is successful this function will return a zero. Returns: nonzero on error. See Also: put,printf Example: int DEVICE::printf(char *format, ... ) {// The printf function from DEVICE char string[200]; va_list ptr; va_start(ptr,format); vsprintf(string,format,ptr); putstr(string); va_end(ptr); return 0; } _________________________________________________________ virtual int reset(void); Description: Reset acts very different based on the device. On most video devices it will clear the screen, while on others it flushes all I/O buffers. Returns: nonzero on error. See Also: goxy. _________________________________________________________ virtual BYTE wait2get(BYTE *ch); Description: ch - if NULL does nothing, otherwise the BYTE read. This function enters a loop to wait for a character to be available then receives the next 8-bit character from the device. There are two paths by which this function returns its data. First is through the normal function return, and second is vi a a pointer to a BYTE. If you do not wish to use the pointer method simply call it as "get(NULL)". Example: "wait2get(NULL)", "wait2get(&x)" and "x=wait2get(&x)" all do exactly the same thing. WARNING: This function can hang the system if no char acter ever becomes available. Returns: character read. See Also: put,getstr,hit. Example: see get. _________________________________________________________ virtual int wherex(void); Description: The wherex function will return the x coordinate of this device. Returns: nonzero on error. See Also: wherey,reset,goxy. Example: void main(void) { DEVICE *device; device=new DEVICE; device->goxy(10,10);// Move cursor device->printf("Cursor is at: %xi,%i.",// Display cursor's location device->wherex(),device->wherey()); } _________________________________________________________ virtual int wherey(void); Description: The wherey function will return the y coordinate of this device. Returns: nonzero on error. See Also: wherex,reset,goxy. Example: void main(void) { DEVICE *device; device=new DEVICE; device->goxy(10,10);// Move cursor device->printf("Cursor is at: %xi,%i.",// Display cursor's location device->wherex(),device->wherey()); } CLASS NAME: COMIO PARENT: DEVICE IMPORTANT CHILDREN: ALP Definition: class COMIO:public DEVICE { public: COMIO(void); ~COMIO(); int init(int p); virtual int put(BYTE ch); virtual BYTE get(BYTE *ch); virtual int putstr(char *str); virtual int hit(void); virtual void baud(long r); virtual void disconnect(void); virtual int timed_get(BYTE *ch,int secs); void flush_out(void); void flush_in(void); void purge_out(void); void purge_out(void); void flow(int i); void dtr(int i); char carrier(void); int direct,no_modem; long lockbaud; long baudrate,bps; private: Varies with operating system. }; Description: COMIO provides a platform-independent method for communicating with the computer's serial ports. COMIO follows the strict interface definition defined by the DEVICE class, and is consistent with all other MULTI-APP classes in that way. You can spec ify many additional arguments that are compatible only with a serial device, yet all serial I/O is compatible with the DEVICE class. Hardware comport numbers always start at 1. Data Members: long baudrate The baud rate that the remote modem is at, regardless of locked baudrate. This must be maintained by the user if it is needed. long bps The port's baud rate, if baud rate is locked then this should never be different than lockbaud. This value is set internally by MultiApp and is meant for reference only. char detect_carrier If this value is true then the carrier function returns the status of the carrier pin. If this value is false then carrier always returns true. int direct If this value is one then the COMIO object will do all of its communication at the most direct level possible. On Mac this would be through the serial manager, on Dos this would mean through interrupts and ports. If this value is zero then the C OMIO object will do all of its communication at a higher level. On Mac this would still be through the serial manager, on dos this would be through BIOS or a FOSSIL if one is loaded. Generally you should set this as 1. WARNING: never change this value once init has been called. long lockbaud This variable allows you to lock the baud rate at some speed. If you set it to zero(the default) then baud rate is variable. Some 9600 baud modems require their baud rate to be locked at 38,400 baud, this function makes the use of such modems ea sier. int no_modem If this variable is set to one then no communication with the serial ports is made. This provides for a sort of test mode. port Serial port number that this instance of COMIO is working with. Member Functions: COMIO(void); Description: CONSTRUCTOR - Allocates any memory needed for buffers. Returns: nothing. See Also: ~COMIO. Example: // VTERM is a simple tty terminal that must be provided with a DEVICE to use // as a console. This console is usually something such as the UI's CONIO object // however it can really be anything, even another COMIO(which would provide a // remote terminal. Press \ for a list of commands in this terminal. void vterm(DEVICE *con,COMIO *com) { // con - console device // com - "modem" interface int done=0; char ch;// Check for commands com->baud(2400);// Default to 2400 baud while(!done) { if(con->hit())// Output keypress { ch=con->get(NULL); if(ch!='\') com->put(con->get(NULL)); } if(com->hit())// Display incoming data con->put(com->get(NULL)); if(ch=='\') { char str[100]; con->reset(); con->putstr("Select an option: <B>aud <D>isconnect or <Q>uit? "); switch( toupper(con->wait2get(NULL))) { case Q':done=1;break; case D':com->disconnect();break; case B':con->putstr("\rWhat baud? "); con->getstr(str); con->baud(atoi(str)); break; } } } } _________________________________________________________ ~COMIO(); Description: DESTRUCTOR - Releases any allocated memory, and closes the hardware serial port. Returns: nothing. See Also: COMIO. _________________________________________________________ virtual void baud(long r); Description: r - The baud rate that you wish to use. Commands the hardware comport to do all I/O at r baud rate. Returns: nonzero on error. See Also: init. Example: see constructor example. _________________________________________________________ virtual void baud(long r); Description: r - The baud rate that you wish to use. Commands the hardware comport to do all I/O at r baud rate. Returns: nonzero on error. See Also: init. Example: see constructor example. _________________________________________________________ virtual void disconnect(void); Description: This function is intended for when the serial port is connected to a hayes compatible modem. Disconnect attempts to break the connection by dropping DTR, if that doesn't work then the classic +++ followed by ATH is sent. Returns: nonzero on error. See Also: dtr. Example: see constructor example. _________________________________________________________ void dtr(int i); Description: i - State of DTR:1=on, 0=off. This function allows you to set the state of the DTR line. Call it with 1 to raise DTR, zero to lower DTR. Returns: nothing. See Also: Example: void COMIO::disconnect() { int i; dtr(0);// Attempt to disconnect using DTR sleep(30); dtr(1) if(!carrier())// If no carrier then we are done return; for(i=0;i<=2;i++) { COMIO::put('+'); sleep(30); } sleep(15); COMIO::putstr("\rATH0\r"); } _________________________________________________________ void flush_in(void); Description: This function will clear out the current inbound buffer, and any characters that may arrive while clearing. It will not return until the hit function returns a zero. Returns: nothing See Also: flush_out,purge_in,purge_out _________________________________________________________ void flush_out(void); Description: This functions for the operating system to transmit any characters waiting in the out buffer. Returns: nothing. See Also: flush_in,purge_in,purge_out _________________________________________________________ virtual BYTE get(BYTE *ch); Description: ch - Pointer to where to store read character(if not NULL). This function receives the next 8-bit character from the serial port. If none are available then this function returns a zero. There are two paths by which this function returns its data. First is through the normal function return, and second i s via a pointer to a BYTE. If you do not wish to use the pointer method simply call it as "get(NULL)". Example: "x=get(NULL)", "get(&x)" and "x=get(&x)" all do exactly the same thing. Returns: character read. See Also: put,getstr,hit. Example: see constructor example. _________________________________________________________ virtual int hit(void); Description: Hit allows you to determine if there is a character waiting to be received(by one of the input functions). Hit returns 0 if none available. If data is waiting it returns the number of bytes waiting. Returns: true if there is a character available. See Also: get,wait2get. Example: see constructor example. _________________________________________________________ int init(int p); Description: p - the comport that you want to use. Opens hardware comport p and attaches it to this object. Returns: nonzero on error. See Also: ~COMIO. Example: see constructor example. _________________________________________________________ void purge_in(void); Description: This function will erase any characters that are currently in the input buffer. Returns: nothing See Also: flush_in,flush_out,purge_out _________________________________________________________ void purge_out(void); Description: This function removes any characters from the output buffer, causing them to never be transmitted. Returns: nothing. See Also: flush_out,flush_in,purge_in _________________________________________________________ virtual int put(BYTE ch); Description: ch - the character to be written. This function will attempt to write a single character to the device. If the operation is successful this function will return a zero. Returns: nonzero on error. See Also: get,putstr,printf. Example: see constructor example. _________________________________________________________ int putstr(char *str); Description: str - the string or modem command. This function is used primarily for modem commands. If the string starts with the letters AT then the string is assumed to be a modem command and some extra processing is done. Otherwise the string is simply written to the serial port. Modem str ings may have the following characters imbedded in them: | (pipe) = carriage return { = carriage return v(lowercase)= drop dtr ^(carrot) = raise dtr Returns: zero on success. See Also: _________________________________________________________ virtual int timed_get(BYTE *ch,int secs); Description: ch - pointer to where to store read character. secs-how many tenths of a second to wait for the character. This function receives the next 8-bit character from the serial port. If none are available then this waits secs 1/10ths of a seconds for one to arrive. If a character was found before timeout this function returns 0, otherwise a one is returned. The actual character is returned by the ch pointer. Returns: nonzero on error. See Also: CLASS NAME: ALP PARENT: COMIO IMPORTANT CHILDREN: none Definition: struct ALP:public COMIO { public: ALP(); void update(void);// Call this as often as possible void intr(void); int check(void); // Check for ALP-compat device on remote side void transmit(void); // transmit a packet // Replacements for CONIO functions: virtual int put(BYTE ch); virtual BYTE get(BYTE *ch); virtual int hit(void); virtual void disconnect(); char str[2000]; int p; BYTE intrans; BYTE no_alp; private: // Incoming queue void push(BYTE ch); BYTE pop(void); void input(BYTE ch); BYTE hi,lo; BYTE in_packet[2048]; BYTE uncomp[2048]; BYTE phase; int in_length; int in_num; unsigned short in_crc; unsigned short in_tcrc; int in_loc; BYTE queue[ALP_IN]; int front,back; int background; BYTE outnum; BYTE lastnum; }; Description: ALP(Anti Line noise Protocol) is a replacement for COMIO that ensures a 2-way reliable serial connection. Data is sent out in packets(which are compressed using the LZSS protocol) that are verified to insure a reliable link. It is 100% compatible with the COMIO object. This communications standard allows separate MULTI-APP applications to have a common hi-level method of communication. When using ALP you can use put,get and all the other COMIO functions and let ALP worry about the error che cking. Except for the update function none of the additional contents of this class are of any real use to the application programmer. Data Members: BYTE intrans; Intrans is a flag that tells if a packet is in transit or not. If a packet is in-transit it means that the packet has been sent, yet ALP is unsure if it made it through correctly or not. Intrans holds 1 if block is in transit, zero if not. BYTE no_alp; no_alp is a flag that tells if ALP is enabled or not. If ALP is disabled then all calls are passed directly through to the COMIO object. int p; P tells ALP how many characters are in the str buffer waiting to go out in the next packet. See str for more details. char str[2000]; This is the buffer where outgoing data is held until it is packeted. This variable is made public because it is perfectly legal to memcopy stuff into str and modify p directly. This is particularly appealing in file transfer situation as it cuts the overhead induced by the COMIO replacements. Member Functions: ALP(); Description: CONSTRUCTOR - The ALP constructor sets up all buffers and initialized all pointers. Returns: nothing. See Also: Example: // VTERM-ALP is a simple tty terminal that must be provided with a DEVICE to use // as a console. This console is usually something such as the UI's CONIO object // however it can really be anything, even another COMIO(which would provide a // remote terminal. Press \ for a list of commands in this terminal. // This example is very similar to the example given in COMIO, this shows how // compatible these two classes are. void vterm(DEVICE *con,ALP *com) { // con - console device // com - "modem" interface int done=0; char ch;// Check for commands com->baud(2400);// Default to 2400 baud while(!done) { com->update();// For ALP to packet everything when needed if(con->hit())// Output keypress { ch=con->get(NULL); if(ch!='\') com->put(con->get(NULL)); } if(com->hit())// Display incoming data con->put(com->get(NULL)); if(ch=='\') { char str[100]; con->reset(); con->putstr("Select an option: <B>aud <D>isconnect,<A>lp or <Q>uit? "); switch( toupper(con->wait2get(NULL))) { case Q':done=1;break; case D':com->disconnect();break; case B':con->putstr("\rWhat baud? "); con->getstr(str); con->baud(atoi(str)); break; case A': if(com->check()) con->putstr("ALP active\r"); break; } } } } _________________________________________________________ int check(void); Description: This function is used to establish an ALP session. Check transmits the ALP init string and waits for a reply. If the other side replies(it does this automatically via update) then both sides no_alp values gets set to zero and an ALP session begi ns. Returns: TRUE if ALP link has been established. See Also: update,intr. Example: see constructor example. _________________________________________________________ virtual void disconnect(void); Description: This function is intended for when the serial port is connected to a hayes compatible modem. Disconnect first ends the ALP session. Then disconnect attempts to break the connection by dropping DTR, if that doesn't work then the classic +++ follow ed by ATH is sent. Returns: nothing. See Also: dtr. Example: see constructor example. _________________________________________________________ void dtr(int i); Description: i - State of DTR:1=on, 0=off. This function allows you to set the state of the DTR line. Call it with 1 to raise DTR, zero to lower DTR. Returns: nothing. See Also: Example: void COMIO::disconnect() { int i; dtr(0);// Attempt to disconnect using DTR sleep(30); dtr(1) if(!carrier())// If no carrier then we are done return; for(i=0;i<=2;i++) { COMIO::put('+'); sleep(30); } sleep(15); COMIO::putstr("\rATH0\r"); } _________________________________________________________ void flow(int i); Description: i - flow control type: 0 = NONE 1 = CTS/RTS(hardware) 2 = XON/XOFF(software) 3 = both hardware and software This function sets the flow control mode of the serial port. This is useful for high speed modems. Returns: nothing. See Also: _________________________________________________________ virtual BYTE get(BYTE *ch); Description: ch - Pointer to where to store read character(if not NULL). This function receives the next 8-bit character from the ALP driver. If none are available then this function returns a zero. There are two paths by which this function returns its data. First is through the normal function return, and second is via a pointer to a BYTE. If you do not wish to use the pointer method simply call it as "get(NULL)". Example: "x=get(NULL)", "get(&x)" and "x=get(&x)" all do exactly the same thing. Returns: the character read. See Also: getstr,put,hit. Example: see constructor example. _________________________________________________________ virtual int hit(void); Description: Hit allows you to determine if there is a character waiting to be received(by one of the input functions). Hit returns 0 if none available. If data is waiting it returns the number of bytes waiting. Returns: the number of characters waiting to be read. See Also: get. Example: see constructor example. _________________________________________________________ void intr(void); Description: Intr is similar to update, except that it is intended to be called from an interrupt if that is how you desire to make sure ALP stays updated. Returns: nothing. See Also: update. _________________________________________________________ virtual int put(BYTE ch); Description: ch - character to be written. This function will attempt to write a single character to the device. If the operation is successful this function will return a zero. Returns: nonzero on error. See Also: printf,putstr. Example: see constructor example. _________________________________________________________ void transmit(void); Description: Transmit will force a packet to be transmitted. Returns: nothing. See Also: _________________________________________________________ void update(void); Description: Update should be called as often as possible, as it checks the incoming data line for packets and transmits any waiting data in a packet. Returns: nothing. See Also: intr. Example: see constructor example. CLASS NAME: FILEIO PARENT: DEVICE IMPORTANT CHILDREN: none Definition: class FILEIO:public DEVICE { public: FILEIO(); ~FILEIO(); int gethandle(void); void open_file(char *path,char *name,char md,char *type,char *creator); void fread(void *loc,long len); void fwrite(void *loc,long len); char end(void); char error(void); void close_file(void); void pos(long loc); long where(void); virtual int put(BYTE ch); virtual BYTE get(BYTE *ch); char sharing; char filename[80]; }; Description: FILEIO provides a platform-independent method for accessing files. It is setup exactly like any other MGBBS DEVICE. Support is provided for file sharing(in platforms that support it). All single character commands are buffered to provide maximum speed. Data Members: char sharing; Holds 1 if file sharing is on, 0 if it is off(set by user). char filename[80]; Holds the full file name(including path). Member Functions: FILEIO(); Description: CONSTRUCTOR - sets up all pointers, handles etc. Returns: nonzero on error. See Also: Example: int copyfile(char *source_path,char *source_name,char *dest_path,char *dest_name) {// This function will copy a file. Please note that this function will only copy the // data fork of a Macintosh File. FILE *in,*out; in=new FILEIO; out=new FILEIO; in->open_file(source_path,source_name,'r',"",""); out->open_file(dest_path,dest_name,'w',"",""); if(in->error() || out->error() ) { delete in;// Delete both file objects(this will close either if they were opened) delete out; return 1;// return an error condition } while(!in->end())// Loop until end-of-file is reached out->put(in->get(NULL)); in->close_file(); out->close_file(); } _________________________________________________________ ~FILEIO(); Description: DESTRUCTOR - closes file if open. Returns: nonzero on error. See Also: _________________________________________________________ void close_file(void); Description: This function will close the file, allowing the same data structure to be used for another file. Returns: nonzero on error. See Also: _________________________________________________________ char end(void); Description: This function returns true if the end of the file has been reached. Returns: nonzero on error. See Also: _________________________________________________________ char error(void); Description: This function returns true if the file is in an error condition. Returns: nonzero on error. See Also: _________________________________________________________ void fwrite(void *loc,long len); Description: loc - The location in memory your writing from. len - The length of the block being written. This function, which is similar to the <stdio.h> function of the same name, allows you to write something pointed to by loc of length len to the file. Returns: nonzero on error. See Also: _________________________________________________________ void fread(void *loc,long len); Description: loc - Pointer to the location in memory to hold block len - The length of the file you wish to read. This function, which is similar to the <stdio.h> function of the same name, allows you to read something into an area pointed to by loc of length len from the file. Returns: nonzero on error. See Also: _________________________________________________________ virtual BYTE get(BYTE *ch); Description: ch - Pointer to where to store read character(if not NULL). This function receives the next 8-bit character from the device. If none are available then this function returns a zero. There are two paths by which this function returns its data. First is through the normal function return, and second is via a pointer to a BYTE. If you do not wish to use the pointer method simply call it as "get(NULL)". Example: "x=get(NULL)", "get(&x)" and "x=get(&x)" all do exactly the same thing. Returns: nonzero on error. See Also: _________________________________________________________ int gethandle(void); Description: Most operating systems use a single integer to reference a file. If the operations system your using MULTI-APP in supports such file referencing this function returns that value. Use of this function should be avoided, as it can cause code created for MULTI-APP to be incompatible on other platforms. Returns: nonzero on error. See Also: _________________________________________________________ void open_file(char *path,char *name,char md,char *type,char *creator); Description: path - The location in the file system of the file. name - The actual name of the file. md - The access mode your using for the file. type - The 4 character file type(only used on some OS's) mode - The 4 character file signature(only used on some OS's) This function is used to tell FILEIO which fill it will be accessing. You can specify both a path and a name. md should be one of the following: r' for reading(other users are allowed to also read) w' for writing and truncation(other users must wait to access file) +' both read and write(other users must wait to access file) s' for both read/write(other uses may have full access to file) a' for appended write(other users must wait to access file) The type and creator allow you to specify these fields if your operating system supports them. The w' command will erase anything that was in the file beforehand. If you wish to write a single record in a file you must open with the +' command, e ven if you will not be reading. Returns: nonzero on error. See Also: _________________________________________________________ void pos(long loc); Description: loc - Location in bytes to place file pointer. This function will position the file position at loc. Returns: nonzero on error. See Also: _________________________________________________________ virtual int put(BYTE ch); Description: ch - The character to be written to the file. This function will attempt to write a single character to the device. If the operation is successful this function will return a zero. Returns: nonzero on error. See Also: _________________________________________________________ long where(void); Description: This function will return the current file position. Returns: nonzero on error. See Also: CLASS NAME: STACK PARENT: NONE IMPORTANT CHILDREN: NONE Definition: class STACK { public: STACK(); int pop(void); void push(int v); int empty(void); private: int location; int stack[STACK_SIZE]; }; Description: Stack sets up a stack(FIFO) to hold integers. This stack may be upto STACK_SIZE in length. Data Members: NONE Member Functions: STACK(); CONSTRUCTOR - sets up a empty stack. int pop(void); Pops an integer from the stack. void push(int v); Pushes an integer onto the stack. int empty(void); This function allows you to tell if a stack is empty. It returns nonzero if the stack has items, zero if there are none. Glossary BAUD - the communication rate between two devices. Baud rates usually range from 300 to 38400 baud. CARRIER - is a signal generated by a remote modem to say that it is still on-line. In any serious communications program carrier must be repeatedly checked to ensure the remote modem is still connected. CREATOR - a file ID used by some operating systems(most notably the Mac) that allows data files to know "who created them." DATA CONTAINER - A dynamic holding area for data that can shrink or grow to handle the amount of data sent. Data containers usually store data in some predetermined way. DTR - The software on/off switch for a modem. If DTR is lowered the modem hangs up and will not accept any commands until the DTR is raised. DYNAMIC - Able to change to meet the situation at hand. Dynamic containers only take up the amount of memory needed. FALSE - A value is said to be false when it contains a zero. FIFO - "First In First Out" a way of describing how a data container works, usually associated with a queue. FILE TYPE - some operating systems(most notably the Mac) allow you to assign a file type to any file you open. HAYES COMPAT - A type of modem that understands the hayes AT style command. A hayes modem receives all its commands over the data lines, rather than the special control lines. INTERRUPT - When the computer stops doing what it was doing to handle something that has happened. INTERRUPT DEVICE - A device that stops the computers processing to handle its changed state. LINE NOISE - Errors that commonly occur in data communication caused by bad phone lines. LIFO - "Last In First Out" a way of describing how a data container works, usually associated with a stack. LINKED LIST - A sort of dynamic array. A linked list holds a series of elements in some predetermined order. MODAL-A window that once on your screen is the only thing that you can access until it is "dismissed." MODELESS-A window that can be moved to the background by clicking another window on the screen. POLLED DEVICE - A device that generates no interrupt when its state changes, but rather must be polled to determine if it is ready. All devices in MULTI-APP are polled. QUEUE - A data container commonly put between to devices of differing speeds. A queue will accept information and release it in the same order as it got it. Think of a queue as a one-way street, only one entrance and only one exit. STACK - A data container commonly used when you want to leave something the same way you came. A stack will accept information and release the last item you entered, then the 2nd to last and so on. Think of a stack as a restaurant plate holder, you can only get the plate on the top. If you want to get the bottom plate you must remove all plates. TRUE - A value is said to be true when it holds any value other than zero.